<div class="article">
   <div class="titlepage">
      <div>
         <h2 class="title"><a name="d5e1"></a>DocBook Extensions For XSLT Stylesheet Documentation
         </h2>
      </div>
      <div>
         <h3 class="author">Steve Ball</h3>
      </div>
      <div>
         <p class="releaseinfo">
            $Id: docbook-extensions.html,v 1.5 2001/11/03 00:50:28 balls Exp $
                
         </p>
      </div>
      <div>
         <p class="copyright">Copyright &copy; 2001 Steve Ball</p>
      </div>
      <hr>
   </div>
   <div class="toc">
      <p><b>Table of Contents</b></p>
      <dl>
         <dt><a href="#d5e17">Introduction</a></dt>
         <dt><a href="#d5e32">Documenting XSLT Stylesheets</a></dt>
         <dd>
            <dl>
               <dt><a href="#d5e37">XML Namespace</a></dt>
               <dt><a href="#d5e45">Toplevel Documentation Element</a></dt>
               <dt><a href="#d5e82">Documenting Templates</a></dt>
            </dl>
         </dd>
         <dt><a href="#reference">Reference</a></dt>
      </dl>
   </div>
   <div class="section"><a name="d5e17"></a><div class="titlepage">
         <div>
            <h2 class="title" style="clear: both"><a name="d5e17"></a>Introduction
            </h2>
         </div>
      </div>
      <p><a href="index.html" target="_top">XSLTSL</a> requires that all stylesheets and templates are documented using <a href="http://www.docbook.org/" target="_top">DocBook</a>, a widely-used electronic documentation standard.  <a href="http://nwalsh.com/" target="_top">Norm Walsh</a> introduced some extensions to DocBook to facilitate documenting XSLT stylesheets, and the stylesheets for DocBook itself
         are documented using this extension.
      </p>
      <p>Further elements have been added to the extension vocabulary for the purpose of documenting XSLTSL stylesheets.  The entire
         extension vocabulary is documented here.
      </p>
   </div>
   <div class="section"><a name="d5e32"></a><div class="titlepage">
         <div>
            <h2 class="title" style="clear: both"><a name="d5e32"></a>Documenting XSLT Stylesheets
            </h2>
         </div>
      </div>
      <p>This section explains how an XSLT stylesheet is documented, with examples.</p>
      <div class="section"><a name="d5e37"></a><div class="titlepage">
            <div>
               <h3 class="title"><a name="d5e37"></a>XML Namespace
               </h3>
            </div>
         </div>
         <p>The XSLT stylesheet must declare an XML Namespace with the namespace URI http://xsltsl.org/xsl/documentation/1.0.  The prefix
            used should then be excluded from the result.  For example:
         </p>
         <div class="informalexample" id="d5e42"><a name="d5e42"></a><pre class="programlisting">
&lt;xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:doc="http://xsltsl.org/xsl/documentation/1.0"
  exclude-result-prefixes="doc"
  version="1.0"&gt;

&lt;/xsl:stylesheet&gt;
</pre></div>
      </div>
      <div class="section"><a name="d5e45"></a><div class="titlepage">
            <div>
               <h3 class="title"><a name="d5e45"></a>Toplevel Documentation Element
               </h3>
            </div>
         </div>
         <p>Major documentation components of the library are contained within the <tt>book</tt> (for the top level) or <tt>chapter</tt> (for lower-level components) elements.  Individual stylesheets are contained within the <tt>reference</tt>.
         </p>
         <p>These elements must be qualified within the stylesheet, but for convenience, the default XML Namespace is redefined so that
            descendant elements need not be qualified.  Within the <tt>book</tt> and <tt>reference</tt> elements all standard DocBook elements are permitted.
         </p>
         <p>An example of library documentation:</p>
         <div class="informalexample" id="d5e69"><a name="d5e69"></a><pre class="programlisting">
&lt;xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:doc="http://xsltsl.org/xsl/documentation/1.0"
  exclude-result-prefixes="doc"
  version="1.0"&gt;

  &lt;doc:book xmlns=""&gt;
    &lt;bookinfo&gt;
      &lt;title&gt;Stylesheet Module For XSLT Standard Library&lt;/title&gt;
      &lt;!-- &amp;#36;Id&amp;#36; --&gt;

      &lt;author&gt;
	&lt;surname&gt;Ball&lt;/surname&gt;
	&lt;firstname&gt;Steve&lt;/firstname&gt;
      &lt;/author&gt;
      &lt;copyright&gt;
	&lt;year&gt;2001&lt;/year&gt;
	&lt;holder&gt;Steve Ball&lt;/holder&gt;
      &lt;/copyright&gt;
    &lt;/bookinfo&gt;

    &lt;preface&gt;
      &lt;para&gt;&lt;ulink url="http://www.w3.org/Style/XSL"&gt;XSLT&lt;/ulink&gt; is an &lt;ulink url="http://www.w3.org/Markup/XML/"&gt;XML&lt;/ulink&gt;-based language for transforming XML documents.&lt;/para&gt;
    &lt;/preface&gt;

    &lt;chapter&gt;
      &lt;title&gt;Reference&lt;/title&gt;

      &lt;para&gt;Stylesheets are documented as DocBook &lt;sgmltag&gt;reference&lt;/sgmltag&gt; elements.&lt;/para&gt;
    &lt;/chapter&gt;
  &lt;/doc:book&gt;

&lt;/xsl:stylesheet&gt;
</pre></div>
         <p>An example of stylesheet documentation:</p>
         <div class="informalexample" id="d5e74"><a name="d5e74"></a><pre class="programlisting">
&lt;xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:doc="http://xsltsl.org/xsl/documentation/1.0"
  exclude-result-prefixes="doc"
  version="1.0"&gt;

  &lt;doc:reference xmlns=""&gt;
    &lt;referenceinfo&gt;
      &lt;releaseinfo role="meta"&gt;
	&amp;#36;Id&amp;#36;
      &lt;/releaseinfo&gt;
      &lt;author&gt;
	&lt;surname&gt;Ball&lt;/surname&gt;
	&lt;firstname&gt;Steve&lt;/firstname&gt;
      &lt;/author&gt;
      &lt;copyright&gt;
	&lt;year&gt;2001&lt;/year&gt;
	&lt;holder&gt;Steve Ball&lt;/holder&gt;
      &lt;/copyright&gt;
    &lt;/referenceinfo&gt;

    &lt;title&gt;String Processing&lt;/title&gt;

    &lt;partintro&gt;
      &lt;section&gt;
	&lt;title&gt;Introduction&lt;/title&gt;

	&lt;para&gt;This module provides templates for manipulating strings.&lt;/para&gt;

      &lt;/section&gt;
    &lt;/partintro&gt;

  &lt;/doc:reference&gt;

</pre></div>
         <p>The keyword <tt>$Id: docbook-extensions.html,v 1.5 2001/11/03 00:50:28 balls Exp $</tt> is used by CVS to insert version and author information.
         </p>
      </div>
      <div class="section"><a name="d5e82"></a><div class="titlepage">
            <div>
               <h3 class="title"><a name="d5e82"></a>Documenting Templates
               </h3>
            </div>
         </div>
         <p>Within each stylesheet, each individual template is documented using a separate toplevel element, <tt>template</tt>.  As for toplevel documentation elements, redeclaring the null XML Namespace allows DocBook elements to be used without qualification.
             A number of extension elements are used to document XSLT templates.  An example of template documentation:
         </p>
         <div class="informalexample" id="d5e94"><a name="d5e94"></a><pre class="programlisting">
  &lt;doc:template name="str:to-upper" xmlns=""&gt;
    &lt;refpurpose&gt;Make string uppercase&lt;/refpurpose&gt;

    &lt;refdescription&gt;
      &lt;para&gt;Converts all lowercase letters to uppercase.&lt;/para&gt;
    &lt;/refdescription&gt;

    &lt;refparameter&gt;
      &lt;variablelist&gt;
	&lt;varlistentry&gt;
	  &lt;term&gt;text&lt;/term&gt;
	  &lt;listitem&gt;
	    &lt;para&gt;The string to be converted&lt;/para&gt;
	  &lt;/listitem&gt;
	&lt;/varlistentry&gt;
      &lt;/variablelist&gt;
    &lt;/refparameter&gt;

    &lt;refreturn&gt;
      &lt;para&gt;Returns string with all uppercase letters.&lt;/para&gt;
    &lt;/refreturn&gt;
  &lt;/doc:template&gt;

  &lt;xsl:template name="str:to-upper"&gt;
    &lt;xsl:param name="text"/&gt;

    &lt;xsl:value-of select="translate($text, $str:lower, $str:upper)"/&gt;
  &lt;/xsl:template&gt;

</pre></div>
      </div>
   </div>
   <div class="section"><a name="reference"></a><div class="titlepage">
         <div>
            <h2 class="title" style="clear: both"><a name="reference"></a>Reference
            </h2>
         </div>
      </div>
      <div class="toc">
         <p><b>Table of Contents</b></p>
         <dl>
            <dt><a href="#xslt.elem.refdescription">Refdescription</a> - A description of the topic of a reference entry
            </dt>
            <dt><a href="#xslt.elem.refparameter">Refparameter</a> - A description of a template parameter.
            </dt>
            <dt><a href="#xslt.elem.parametername">Parametername</a> - A parameter name.
            </dt>
            <dt><a href="#xslt.elem.refreturn">Refreturn</a> - The return result of a template.
            </dt>
            <dt><a href="#xslt.elem.refexception">Refexception</a> - An exception generated by the template.
            </dt>
         </dl>
      </div>
      <p>Reference documentation for all extension elements.</p>
      <hr>
      <div class="refentry">
         <h1 class="title"><a name="xslt.elem.refdescription"></a>Refdescription
         </h1>
         <div class="refnamediv"><a name="d5e113"></a><h2>Name</h2>Refdescription &#8212; A description of the topic of a reference entry
         </div>
         <div class="refsynopsisdiv"><a name="d5e118"></a><h2>
               <h1 class="title"><a name="d5e118"></a>Synopsis
               </h1>
            </h2>
            <div class="informaltable" id="d5e121"><a name="d5e121"></a><table border="1">
                  <colgroup>
                     <col>
                     <col>
                     <col>
                  </colgroup>
                  <tbody>
                     <tr>
                        <td colspan="3" align="left"><span class="bold"><b>Element Content Model</b></span></td>
                     </tr>
                     <tr>
                        <td colspan="3" align="left"><pre class="synopsis">refdescription ::=
(para|...)</pre></td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Attributes</b></span></td>
                        <td colspan="2">Common attributes</td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Parameter Entities</b></span></td>
                     </tr>
                     <tr>
                        <td>None</td>
                     </tr>
                  </tbody>
               </table>
            </div>
         </div>
         <div class="refsect1"><a name="d5e148"></a><h2>Description</h2>
            <p>A description of a reference entry.</p>
            <div class="refsect2"><a name="d5e153"></a><h3>Processing Expectations</h3>
               <p>Formatted as a block.</p>
            </div>
         </div>
         <div class="refsect1"><a name="d5e158"></a><h2>See Also</h2>
            <p><span class="simplelist"><tt>refdescriptor</tt></span></p>
         </div>
         <div class="refsect1"><a name="d5e166"></a><h2>Examples</h2>
            <div class="informalexample" id="d5e169"><a name="d5e169"></a><pre class="programlisting">
    &lt;refdescription&gt;
      &lt;para&gt;Converts all lowercase letters to uppercase.&lt;/para&gt;
    &lt;/refdescription&gt;
</pre></div>
         </div>
      </div>
      <hr>
      <div class="refentry">
         <h1 class="title"><a name="xslt.elem.refparameter"></a>Refparameter
         </h1>
         <div class="refnamediv"><a name="d5e183"></a><h2>Name</h2>Refparameter &#8212; A description of a template parameter.
         </div>
         <div class="refsynopsisdiv"><a name="d5e188"></a><h2>
               <h1 class="title"><a name="d5e188"></a>Synopsis
               </h1>
            </h2>
            <div class="informaltable" id="d5e191"><a name="d5e191"></a><table border="1">
                  <colgroup>
                     <col>
                     <col>
                     <col>
                  </colgroup>
                  <tbody>
                     <tr>
                        <td colspan="3" align="left"><span class="bold"><b>Element Content Model</b></span></td>
                     </tr>
                     <tr>
                        <td colspan="3" align="left"><pre class="synopsis">refparameter ::=
(variablelist)</pre></td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Attributes</b></span></td>
                        <td colspan="2">Common attributes</td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Parameter Entities</b></span></td>
                     </tr>
                     <tr>
                        <td>None</td>
                     </tr>
                  </tbody>
               </table>
            </div>
         </div>
         <div class="refsect1"><a name="d5e218"></a><h2>Description</h2>
            <p>A list of the parameters accepted by a stylesheet template.  Each <tt>varlistentry</tt> in the list names the parameter in its <tt>term</tt> child element, and a description of the parameter in its <tt>listitem</tt> child element.
            </p>
            <div class="refsect2"><a name="d5e232"></a><h3>Processing Expectations</h3>
               <p>Formatted as a block.</p>
            </div>
         </div>
         <div class="refsect1"><a name="d5e237"></a><h2>See Also</h2>
            <p><span class="simplelist"><tt>refreturn</tt></span></p>
         </div>
         <div class="refsect1"><a name="d5e245"></a><h2>Examples</h2>
            <div class="informalexample" id="d5e248"><a name="d5e248"></a><pre class="programlisting">
    &lt;refparameter&gt;
      &lt;variablelist&gt;
	&lt;varlistentry&gt;
	  &lt;term&gt;text&lt;/term&gt;
	  &lt;listitem&gt;
	    &lt;para&gt;The string to be converted&lt;/para&gt;
	  &lt;/listitem&gt;
	&lt;/varlistentry&gt;
      &lt;/variablelist&gt;
    &lt;/refparameter&gt;
</pre></div>
         </div>
      </div>
      <hr>
      <div class="refentry">
         <h1 class="title"><a name="xslt.elem.parametername"></a>Parametername
         </h1>
         <div class="refnamediv"><a name="d5e262"></a><h2>Name</h2>Parametername &#8212; A parameter name.
         </div>
         <div class="refsynopsisdiv"><a name="d5e267"></a><h2>
               <h1 class="title"><a name="d5e267"></a>Synopsis
               </h1>
            </h2>
            <div class="informaltable" id="d5e270"><a name="d5e270"></a><table border="1">
                  <colgroup>
                     <col>
                     <col>
                     <col>
                  </colgroup>
                  <tbody>
                     <tr>
                        <td colspan="3" align="left"><span class="bold"><b>Mixed Content Model</b></span></td>
                     </tr>
                     <tr>
                        <td colspan="3" align="left"><pre class="synopsis">Parametername ::=
(#PCDATA)</pre></td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Attributes</b></span></td>
                        <td colspan="2">Common attributes</td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Parameter Entities</b></span></td>
                     </tr>
                     <tr>
                        <td>None</td>
                     </tr>
                  </tbody>
               </table>
            </div>
         </div>
         <div class="refsect1"><a name="d5e297"></a><h2>Description</h2>
            <p>A parameter name occurring in running text.</p>
            <div class="refsect2"><a name="d5e302"></a><h3>Processing Expectations</h3>
               <p>Formatted inline.</p>
            </div>
         </div>
         <div class="refsect1"><a name="d5e307"></a><h2>See Also</h2>
            <p><span class="simplelist"><tt>refparameter</tt></span></p>
         </div>
         <div class="refsect1"><a name="d5e315"></a><h2>Examples</h2>
            <div class="informalexample" id="d5e318"><a name="d5e318"></a><pre class="programlisting">
&lt;para&gt;A parameter which contains a string value is named &lt;parametername&gt;text&lt;/parametername&gt;.&lt;/para&gt;
</pre></div>
         </div>
      </div>
      <hr>
      <div class="refentry">
         <h1 class="title"><a name="xslt.elem.refreturn"></a>Refreturn
         </h1>
         <div class="refnamediv"><a name="d5e332"></a><h2>Name</h2>Refreturn &#8212; The return result of a template.
         </div>
         <div class="refsynopsisdiv"><a name="d5e337"></a><h2>
               <h1 class="title"><a name="d5e337"></a>Synopsis
               </h1>
            </h2>
            <div class="informaltable" id="d5e340"><a name="d5e340"></a><table border="1">
                  <colgroup>
                     <col>
                     <col>
                     <col>
                  </colgroup>
                  <tbody>
                     <tr>
                        <td colspan="3" align="left"><span class="bold"><b>Element Content Model</b></span></td>
                     </tr>
                     <tr>
                        <td colspan="3" align="left"><pre class="synopsis">refparameter ::=
(para+)</pre></td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Attributes</b></span></td>
                        <td colspan="2">Common attributes</td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Parameter Entities</b></span></td>
                     </tr>
                     <tr>
                        <td>None</td>
                     </tr>
                  </tbody>
               </table>
            </div>
         </div>
         <div class="refsect1"><a name="d5e367"></a><h2>Description</h2>
            <p>Describes the return result of the stylesheet template.</p>
            <div class="refsect2"><a name="d5e372"></a><h3>Processing Expectations</h3>
               <p>Formatted as a block.</p>
            </div>
         </div>
         <div class="refsect1"><a name="d5e377"></a><h2>See Also</h2>
            <p><span class="simplelist"><tt>refparameter</tt>, <tt>refreturn</tt></span></p>
         </div>
         <div class="refsect1"><a name="d5e388"></a><h2>Examples</h2>
            <div class="informalexample" id="d5e391"><a name="d5e391"></a><pre class="programlisting">
    &lt;refreturn&gt;
      &lt;para&gt;Returns string with all uppercase letters.&lt;/para&gt;
    &lt;/refreturn&gt;
</pre></div>
         </div>
      </div>
      <hr>
      <div class="refentry">
         <h1 class="title"><a name="xslt.elem.refexception"></a>Refexception
         </h1>
         <div class="refnamediv"><a name="d5e405"></a><h2>Name</h2>Refexception, Refthrows &#8212; An exception generated by the template.
         </div>
         <div class="refsynopsisdiv"><a name="d5e412"></a><h2>
               <h1 class="title"><a name="d5e412"></a>Synopsis
               </h1>
            </h2>
            <div class="informaltable" id="d5e415"><a name="d5e415"></a><table border="1">
                  <colgroup>
                     <col>
                     <col>
                     <col>
                  </colgroup>
                  <tbody>
                     <tr>
                        <td colspan="3" align="left"><span class="bold"><b>Element Content Model</b></span></td>
                     </tr>
                     <tr>
                        <td colspan="3" align="left"><pre class="synopsis">refparameter ::=
(para+)</pre></td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Attributes</b></span></td>
                        <td colspan="2">Common attributes</td>
                     </tr>
                     <tr>
                        <td><span class="bold"><b>Parameter Entities</b></span></td>
                     </tr>
                     <tr>
                        <td>None</td>
                     </tr>
                  </tbody>
               </table>
            </div>
         </div>
         <div class="refsect1"><a name="d5e442"></a><h2>Description</h2>
            <p>Describes any exceptions generated by the stylesheet template.</p>
            <div class="refsect2"><a name="d5e447"></a><h3>Processing Expectations</h3>
               <p>Formatted as a block.</p>
            </div>
         </div>
         <div class="refsect1"><a name="d5e452"></a><h2>See Also</h2>
            <p><span class="simplelist"><tt>refreturn</tt></span></p>
         </div>
         <div class="refsect1"><a name="d5e460"></a><h2>Examples</h2>
            <div class="informalexample" id="d5e463"><a name="d5e463"></a><pre class="programlisting">
    &lt;refexception&gt;
      &lt;para&gt;An error exception is generated if the nodeset is empty.&lt;/para&gt;
    &lt;/refexception&gt;
</pre></div>
         </div>
      </div>
   </div>
</div>